ExtJS Grid Page Functionality

Introduction

Compared to standard Websydian, the way grid pages works has been changed significantly in the Ext JS for WebsydianExpress frameswork. This document provides a detailed explanation of this functionality.

The functions that implement this functionality all inherit from ExtWebGridPage - either directly or through abstract functions that inherit from ExtWebGridPage (e.g. ExtWebDropDown).

In standard Websydian, the grid PageGenerator reads the HTML template - and when the <!-- /(Grid) --> marker is reached, it will start retrieving the grid records, which would then be returned as part of the HTTP response generated by the PageGenerator.

In the Ext JS framework, this behavior has been significantly changed - now the first call to the PageGenerator will return JavaScript that creates an Ext JS grid control on the page. This control will then send it's own HTTP request for data.

We have chosen to let the ExtGridPageGenerator be called for both of these HTTP requests - as this enables you to have the same definitions for an EXTWebGridPage as you would for a standard WebGridPage.

However, even though the Plex definitions are the same as you would create for a standard Websydian GridPageGenerator, the developer needs to be aware of the changed behavior to be able to diagnose any problems that occur when implementing functions that inherit from ExtWebGridPage.

Functionality

The following diagram shows the basic behavior of the ExtWebGridPage and the rest of the functions used when loading the grid.

Loading the ExtWebGridPage

Detailed description

1. Initial request is sent to WebsydianExpress

• The user presses an item in the menu. The browser sends an HTTP request to the application. The request will be handled by a ProcessEntryPoint.
  A new feature introduced with the Ext JS framework for WebsydianExpress is that the requests can specify the type of response the PageGenerator must return.
• Technically, this determines which template the PageGenerator will use. In this case the specified response type is "EXTJS", which means that the PageGenerator must use the template with the file extension ".json.js".
• This step could also have been initiated by pressing a button. In this case it would be an EventHandler that would call the ExtWebGridPage instead of the ProcessEntryPoint.

2. ProcessEntryPoint calls ExtWebGridPageGenerator

• The ProcessEntryPoint calls the ExtWebGridPageGenerator. But before doing so, it writes the response type from the request to memory so that it will be available for the PageGenerator without having to add this parameter to the interface of the PageGenerator.
• The ExtWebGridPageGenerator reads the response type from memory. Based on the response type it resolves the file extension of the template it must use, as well as the content type it must specify for the HTTP response. This information is retrieved and resolved in the function WSYBASE/GetResponseDefaults.
  In this case, it will use the template with the extension ".json.js".
• The ExtWebGridPageGenerator reads the ".json.js" template file and performs the replacement as in a standard Websydian PageGenerator. The special circumstance here is that even though this is a grid page, the template will not contain any /(Grid) markers - so the PageGenerator will never retrieve the grid data. Instead, the template contains definitions of an Ext JS grid component that will be returned to the browser as part of the HTTP response.
• The ExtWebGridPageGenerator returns the HTTP response containing the detail information / detail events and the definitions for the empty grid component.

3. Ext JS renders the grid and sends a request for the data

• The browser loads the HTTP response returned by the ExtWebGridPageGenerator.
• When the page is loaded, an event makes the grid component request data for the grid.
• This results in a new HTTP request. This time the response type "JSON" will be specified - indicating that the PageGenerator should use the template with the file extension ".json". The framework ensures that the request is sent for the EventHandler that has been defined for the "Position" event of the grid.

4. LoadData eventhandler calls the ExtWebGridPageGenerator

• The LoadData EventHandler retrieves the response type and writes it to memory. Then it calls the ExtWebGridPageGenerator again. It is important to note that the ExtWebGridPage function is the same function that was called in step 2.
• The ExtWebGridPageGenerator reads the repsonse type etc. as described in step 4. Based on this information it finds that it must use the ".json" template to generate the HTTP response.
  The ExtWebGridPageGenerator reads the ".json" template. This does contain /(Grid) markers - so the PageGenerator will call the BlockFetch function as needed to retrieve the set of records it must return.
• The ExtWebGridPageGenerator returns the response to the browser - or more precisely to the store used by the grid control.

5. Ext JS loads and renders the data into the grid

• The grid control uses the returned records to populate the grid.

Considerations

For developers, the first thing to note of is that the base definitions in Plex hasn't changed at all. Both the details and the grid fields are defined in the ExtWebGridPageGenerator - as WsyDetails and WsyGrid fields - just as in standard Websydian.

The use and replacement of views and BlockFetch functions for the ExtWebGridPageGenerator function is also exactly the same as in standard Websydian. With the one important difference: To support the way the grid loads more data when you scroll down your BlockFetch function must inherit from either DataAccessRRN.Fetch.BlockFetchRRNWrapper or RRNEntityRelationalTable.Fetch.WsyStatelessBlockFetchRRN.

The main change you need to consider when developing is if you enter handling of the detail region that should only be performed once for each load of the page.

As described above, the ExtWebGridPageGenerator will be called twice when the page is loaded. If you for instance have a counter that should be incremented each time a user loads a page, you must ensure that this only happens on the first call - or the amounts will be doubled.

You can distinguish between the two calls by checking on the local field Document<ResponseType>. This is populated using the response type that was written to meory by the ProcessEntryPoint or the EventHandler. It is possible that the response type for the first call can have another value than EXTJS, but the second call will always have the value JSON. So if you have functionality that should only be performed on the first call, you should perform this in a conditional block that is performed when Document<ResponseType> is not equal to <ResponseType.EXTJS>.

The one situation where the new functionality will have the highest impact is when debugging. You must be aware of the fact that the function will be called twice - and that it may be processed in two separate jobs/processes - or the behavior you see will be hard/impossible to understand.

Loading additional grid records

The diagram and detailed steps description above describes the initial load of the page and the grid data. As for most standard Websydian grids, the entire content of the grid is not loaded when the page is first loaded.

In standard Websydian, the page would contain a "Next" event that would be used to retrieve the next set of records to show in the list. Pressing Next would reload the entire page.

In the ExtWebGridPage functions, this behavior is also changed - but mostly in the client (browser) part. The "Next" event no longer exists - so there no longer is a "Next" button on the page.

Instead the grid control has a scrollbar that is shown if there are more data in the grid than can be seen on the page. When you scroll down, and nearly reaches the end of the data shown, the grid component will automatically request more data - and steps 7 to 13 in the detailed description will be performed again.

Only the grid content is loaded when more data has been retrieved - the page itself is not reloaded.

Sorting grid records

The Ext JS grid component contains functionality to sort the content of the grid without retrieving the records again from the backend system. This means that this possibility also is available in the implementation of the grid control used by the WebsydianExpress Ext JS framework. However, it is important to note that the sort only is performed on the records already loaded to the grid.

• If you have loaded the start of the grid and scrolled down to the end of the grid before sorting the records, you will get all the data sorted as you want it.
• If you have loaded the start of the grid - and maybe scrolled down to get additional (but not all) grid records, only the records already shown in the grid will be sorted. If you then scroll down to get more data, you will get the next set of data based on the original sort of the grid (defined by the view used by the ExtWebGridPage) these data will be mixed into the grid content according to the specified sort criterion.